/*
 * Copyright (C) 2009-2011 Knowings
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License version 3
 * as published by the Free Software Foundation.
 *

 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.

 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 */
package com.knowings.tbs.options;

import java.io.Serializable;
import java.util.Map;

import com.knowings.tbs.NoSuchObjectException;
import com.knowings.tbs.operation.InvalidParameterException;
import com.knowings.tbs.operation.MissingParameterException;
import com.knowings.tbs.operation.UnsupportedLanguageException;
import com.knowings.tbs.permission.PermissionException;
import com.knowings.tbs.trace.IncompatibleTemporalDomainsException;
import com.knowings.tbs.transformation.TransformationRuntimeException;

/**
 * Interface describing the features implemented when a TBS Kernel declares the
 * ITBSKernel.OPTION_CONTINUOUS_TRANSFORMATIONS_SUPPORTED.
 * 
 * @author privarola
 *
 */
public interface IContinuousTransformationsOption {

  /**
   * Method executing a transformation to generate a trace from one or several other.
   * The first operation before the transformation execution is to ensure all involved traces are up-to-date
   * and make a fusion of them.
   * The resulting trace will be stored in the trace repository as a <code>ITransformedTrace</code> instance
   * with an association on a <code>ITransformationExecution</code> instance referencing the used <code>Transformation</code>.
   * If any of the source trace, or the transformation, is modified, the resulting trace will be kept up-to-date
   * every time it is referenced or requested. The way this trace should be updated is left free and it can be
   * done in lazy or eager mode. Keep in mind that breaking the monotony of any of the components involved
   * in this transformation implies a full re-computation of the resulting trace.
   * @param trace_uids the uids of the traces to be taken into account (and merged) as data source for the transformation
   * @param transformation_uid the UID of the stored transformation to be executed
   * @param parameters a map containing parameter names as keys and parameter values as values
   * @return the UID of the resulting <code>ITransformedTrace</code> instance
   * @throws NoSuchObjectException if the query UID is not found or if any of the source trace UID is not found
   * @throws PermissionException if the connected user does not have the right to access a source trace, the transformation,
   * or to create a trace in this workspace
   * @throws UnsupportedLanguageException if the transformation language is not supported
   * @throws MissingParameterException if a transformation mandatory parameter is not given in the parameters map
   * @throws InvalidParameterException if a transformation parameter does not have the expected type
   * @throws IncompatibleTemporalDomainsException if a the source traces does not share the same temporal domain or origin
   * @throws TransformationRuntimeException if the transformation fails due to a syntax problem or internal error
   */
  public String executeContinuousTransformation(String[] trace_uids, String transformation_uid,
      Map<String, Serializable> parameters) throws NoSuchObjectException, PermissionException,
      UnsupportedLanguageException, MissingParameterException, InvalidParameterException,
      IncompatibleTemporalDomainsException, TransformationRuntimeException;

}
